8.4.2 The clock table

Org mode can produce quite complex reports based on the time clocking information. Such a report is called a clock table, because it is formatted as one or several Org tables.

C-c C-x C-r     (org-clock-report)

Insert a dynamic block (see Dynamic blocks) containing a clock report as an Org-mode table into the current file. When the cursor is at an existing clock table, just update it. When called with a prefix argument, jump to the first clock report in the current document and update it.

C-c C-c or C-c C-x C-u     (org-dblock-update)

Update dynamic block at point. The cursor needs to be in the #+BEGIN line of the dynamic block.

C-u C-c C-x C-u

Update all dynamic blocks (see Dynamic blocks). This is useful if you have several clock table blocks in a buffer.

S-<left>

S-<right>     (org-clocktable-try-shift)

Shift the current :block interval and update the table. The cursor needs to be in the #+BEGIN: clocktable line for this command. If :block is today, it will be shifted to today-1 etc.

Here is an example of the frame for a clock table as it is inserted into the buffer with the C-c C-x C-r command:

     #+BEGIN: clocktable :maxlevel 2 :emphasize nil :scope file
     #+END: clocktable

The ‘BEGIN’ line and specify a number of options to define the scope, structure, and formatting of the report. Defaults for all these options can be configured in the variable org-clocktable-defaults.

First there are options that determine which clock entries are to be selected:

     :maxlevel    Maximum level depth to which times are listed in the table.
                  Clocks at deeper levels will be summed into the upper level.
     :scope       The scope to consider.  This can be any of the following:
                  nil        the current buffer or narrowed region
                  file       the full current buffer
                  subtree    the subtree where the clocktable is located
                  treeN      the surrounding level N tree, for example tree3
                  tree       the surrounding level 1 tree
                  agenda     all agenda files
                  ("file"..) scan these files
                  file-with-archives    current file and its archives
                  agenda-with-archives  all agenda files, including archives
     :block       The time block to consider.  This block is specified either
                  absolute, or relative to the current time and may be any of
                  these formats:
                  2007-12-31    New year eve 2007
                  2007-12       December 2007
                  2007-W50      ISO-week 50 in 2007
                  2007-Q2       2nd quarter in 2007
                  2007          the year 2007
                  today, yesterday, today-N          a relative day
                  thisweek, lastweek, thisweek-N     a relative week
                  thismonth, lastmonth, thismonth-N  a relative month
                  thisyear, lastyear, thisyear-N     a relative year
                  Use S-<left>/<right> keys to shift the time interval.
     :tstart      A time string specifying when to start considering times.
     :tend        A time string specifying when to stop considering times.
     :step        week or day, to split the table into chunks.
                  To use this, :block or :tstart, :tend are needed.
     :stepskip0   Do not show steps that have zero time.
     :fileskip0   Do not show table sections from files which did not contribute.
     :tags        A tags match to select entries that should contribute.

Then there are options which determine the formatting of the table. There options are interpreted by the function org-clocktable-write-default, but you can specify your own function using the :formatter parameter.

     :emphasize   When t, emphasize level one and level two items.
     :link        Link the item headlines in the table to their origins.
     :narrow      An integer to limit the width of the headline column in
                  the org table.  If you write it like ‘50!’, then the
                  headline will also be shortened in export.
     :indent      Indent each headline field according to its level.
     :tcolumns    Number of columns to be used for times.  If this is smaller
                  than :maxlevel, lower levels will be lumped into one column.
     :level       Should a level number column be included?
     :compact     Abbreviation for :level nil :indent t :narrow 40! :tcolumns 1
                  All are overwritten except if there is an explicit :narrow
     :timestamp   A timestamp for the entry, when available.  Look for SCHEDULED,
                  DEADLINE, TIMESTAMP and TIMESTAMP_IA, in this order.
     :formula     Content of a #+TBLFM line to be added and evaluated.
                  As a special case, ‘:formula %’ adds a column with % time.
                  If you do not specify a formula here, any existing formula
                  below the clock table will survive updates and be evaluated.
     :formatter   A function to format clock data and insert it into the buffer.

To get a clock summary of the current level 1 tree, for the current day, you could write

     #+BEGIN: clocktable :maxlevel 2 :block today :scope tree1 :link t
     #+END: clocktable

and to use a specific time range you could write¹

     #+BEGIN: clocktable :tstart "<2006-08-10 Thu 10:00>"
                         :tend "<2006-08-10 Thu 12:00>"
     #+END: clocktable

A summary of the current subtree with % times would be

     #+BEGIN: clocktable :scope subtree :link t :formula %
     #+END: clocktable

A horizontally compact representation of everything clocked during last week would be

     #+BEGIN: clocktable :scope agenda :block lastweek :compact t
     #+END: clocktable